Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Creating and Manipulating Shape Objects

GXCacheShape

You can use the GXCacheShape function to prepare a shape for faster drawing.

void GXCacheShape(gxShape source);

source

A reference to the shape to build the cache for.

DESCRIPTION

The GXCacheShape function prepares a shape for drawing by performing the calculations necessary to draw the shape and storing them in a shape cache. Then, when you draw the shape, time is saved because those calculations have already been made.

Although you do not need to call this function before drawing, you can use it to improve the speed of drawing on the screen.

To build a shape cache, use this function. To delete a shape cache, use the GXDisposeShapeCache function. To determine the amount of memory occupied by a shape cache, use the GXGetShapeCacheSize function.

SPECIAL CONSIDERATIONS

If you set the gxCachedShape attribute for a shape, QuickDraw GX automatically creates a cache and a compressed offscreen bitmap for the shape the first time it draws the shape. Unlike calling GXCacheShape, setting the gxCachedShape attribute can result in increased memory requirements for a shape.

ERRORS, WARNINGS, AND NOTICES

Because it performs preliminary calculations involved in drawing, the GXCacheShape function can, in addition to the errors listed below, post any errors and warnings associated with the GXDrawShape function. Therefore, GXCacheShape can post font-related errors if it is caching text.

Errors
out_of_memory
shape_is_nil
number_of_contours_exceeds_implementation_limit
number_of_points_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
size_of_path_exceeds_implementation_limit
size_of_bitmap_exceeds_implementation_limit
pattern_lattice_out_of_range	(debugging version)
Warnings
character_substitution_took_place
graphic_type_cannot_be_dashed	(debugging version)
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
unable_to_draw_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
face_override_style_font_must_match_style	(debugging version)

SEE ALSO

Shape caches are discussed in the section "Caching Shape Objects" beginning on page 2-27. The gxCachedShape attribute is described in that section and also in
Table 2-4 on page 2-16.

The GXGetShapeCacheSize function is described on page 2-64. The GXDisposeShapeCache function is described in the next section.

For information about the caching and drawing typographic shapes, see the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography.